Error Handling(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 2 - Core Printing Features / Using Core Printing Features

Error Handling
QuickDraw GX provides you with an error-handling method to poll for printing-related errors. In previous versions of the Macintosh printing architecture, errors were handled using the PrError function. This function returned the error status. Printing errors were global to an application. In QuickDraw GX, an error is local to a job object.
You can poll for errors in two different ways: immediately after you call a function or after you call groups of functions. QuickDraw GX provides the GXGetJobError function to allow you to poll for errors in both ways.
When an error occurs, the error is stored in the error property of the job object. The error is not cleared until you call the GXGetJobError function. Thus, GXGetJobError returns the first error since the last call to the GXGetJobError function.

IMPORTANT
If an error condition exists for a job object, QuickDraw GX will not execute other functions associated with the job object until the error condition is cleared.
You should note that it is necessary for you to check for errors after certain functions. For example, you should always check for errors after calling functions that begin with the word Start or functions related to collection objects. Functions related to collection objects are discussed in the chapter "Page Formatting and Dialog Box Customization" in this book.
Polling for errors is a standard Macintosh method used by the Resource Manager and the Macintosh Printing Manager. For information on the Resource Manager, see Inside Macintosh: More Macintosh Toolbox. For information on QuickDraw, see Inside Macintosh: Imaging.
Listing 2-2 shows an example of polling for errors by calling GXGetJobError after individual functions. The error conditions being checked for in the example can arise while executing the print loop. For a discussion of the print loop, see "Printing Documents Using QuickDraw GX" beginning on page 2-20.
Listing 2-2 Polling for errors after individual functions
GXGetJobPageRange(myDocument->documentJob, &firstPage, &lastPage);
err = GXGetJobError(myDocument->documentJob);
if (err == noErr)
{
   if (lastPage > myDocument->numPages)
      lastPage = myDocument->numPages;
   numPages = lastPage - firstPage + 1;

   GXStartJob(myDocument->documentJob, 
            myDocument->documentTitle, numPages);
   err = GXGetJobError(myDocument->documentJob);
   if (err == noErr)
   {
      for (pg = firstPage; (err == noErr) && (pg <= 
                                             lastPage); pg++)
      {
         GXPrintPage(myDocument->documentJob, pg,
                  GXGetJobFormat(myDocument->documentJob, 1),
                  myDocument->documentPage[pg -1]);
         err = GXGetJobError(myDocument->documentJob);
      }
      GXFinishJob(myDocument->documentJob);
      err = GXGetJobError(myDocument->documentJob);
   }
}
Listing 2-3 shows an example of polling for errors after groups of functions. This example shows how to obtain the dimensions of the paper and page associated with a format object, which is explained on page 2-33. If the GXGetJobFormat function returns an error, the GXGetFormatDimensions function returns immediately without executing.
Listing 2-3 Polling for errors after groups of functions
OSErr MyGetFormatDimensions(MyDocumentPtr myDocument,
                              gxRectangle *pageBounds, 
                              gxRectangle *paperBounds)
{
   long           curPage;
   gxFormat       pgFormat;

/*
   Get the format object for the current page. If it is nil, use 
   the default format.
*/
   curPage = myDocument->curPage;
   pgFormat = myDocument->pageFormat[curPage -1];
   if (pgFormat == nil)
      pgFormat = GXGetJobFormat(myDocument->documentJob, 1);

/* Get the bounds of the format object.*/
   GXGetFormatDimensions(pgFormat, pageBounds, paperBounds);

   return GXGetJobError(myDocument->documentJob);
}
Unless otherwise indicated, errors are generally checked after groups of functions throughout the code samples in this book.
In addition, QuickDraw GX allows you to store an error with a particular job object using the GXSetJobError function. This function is useful when you want to abort or cancel spooling, which is how data is sent to the printer driver. Spooling is discussed in the chapter "Introduction to Printing With QuickDraw GX" in this book.
The following statement sets the error condition associated with the job object to the contents of err:
   GXSetJobError(myDocument->documentJob, err);
When the error status is tested using GXGetJobError, it will return the status set by the GXSetJobError function, assuming that another error did not occur between the time the value was set and then retrieved.